
/*
 * Copyright 2002-2018 the original author or authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      https://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
/*
 *版权所有2002-2018原创作者。
 *
 *根据Apache许可证2.0版许可（“许可证”）；
 *除非符合许可证的规定，否则您不得使用此文件。
 *您可以在以下网址获取许可证副本：
 *
 *https://www.apache.org/licenses/LICENSE-2.0
 *
 *除非适用法律要求或书面同意，软件
 *根据许可证进行的分发是在“按原样”的基础上进行的，
 *无任何明示或暗示的保证或条件。
 *有关管理权限的特定语言，请参阅许可证和
 *许可证下的限制。
 */

package org.springframework.jndi;

import javax.naming.NamingException;

import org.springframework.lang.Nullable;
import org.springframework.util.Assert;

/**
 * Convenient superclass for classes that can locate any number of JNDI objects.
 * Derives from JndiAccessor to inherit the "jndiTemplate" and "jndiEnvironment"
 * bean properties.
 *
 * <p>JNDI names may or may not include the "java:comp/env/" prefix expected
 * by Jakarta EE applications when accessing a locally mapped (ENC - Environmental
 * Naming Context) resource. If it doesn't, the "java:comp/env/" prefix will
 * be prepended if the "resourceRef" property is true (the default is
 * <strong>false</strong>) and no other scheme (e.g. "java:") is given.
 *
 * @author Juergen Hoeller
 * @since 1.1
 * @see #setJndiTemplate
 * @see #setJndiEnvironment
 * @see #setResourceRef
 */
/**
 *方便的超类，用于可以定位任意数量JNDI对象的类。
 *从JndiAccessor派生以继承“jndiTemplate”和“jndiEnvironment”
 *bean属性。
 *
 *<p>JNDI名称可能包含也可能不包含预期的“java:comp/env/”前缀
 *通过雅加达EE应用程序访问本地映射（ENC-Environmental
 *命名上下文）资源。如果没有，“java:comp/env/”前缀将
 *如果“resourceRef”属性为true（默认值为
 *<strong>false</strong>），并且没有给出其他方案（例如“java:”）。
 *
 *@作者于尔根·霍勒
 *@自1.1起
 *@参见#setJndiTemplate
 *@参见#setJndiEnvironment
 *@参见#setResourceRef
 */
public abstract class JndiLocatorSupport extends JndiAccessor {

	/** JNDI prefix used in a Jakarta EE container. */
	public static final String CONTAINER_PREFIX = "java:comp/env/";


	private boolean resourceRef = false;


	/**
	 * Set whether the lookup occurs in a Jakarta EE container, i.e. if the prefix
	 * "java:comp/env/" needs to be added if the JNDI name doesn't already
	 * contain it. Default is "false".
	 * <p>Note: Will only get applied if no other scheme (e.g. "java:") is given.
	 */
	/** JNDI prefix used in a Jakarta EE container. */
	public static最终字符串CONTAINER_PREFIX=“java:comp/env/”；


	private boolean resourceRef=false；


	/**
	 *设置查找是否发生在Jakarta EE容器中，即如果前缀
	 *如果JNDI名称尚未添加，则需要添加“java:comp/env/”
	 *包含它。默认值为“false”。
	 *<p>注意：只有在没有给出其他方案（例如“java:”）的情况下才会应用。
	 */
	public void setResourceRef(boolean resourceRef) {
		this.resourceRef = resourceRef;
	}

	/**
	 * Return whether the lookup occurs in a Jakarta EE container.
	 */
	/**
	 *返回查找是否发生在Jakarta EE容器中。
	 */
	public boolean isResourceRef() {
		return this.resourceRef;
	}


	/**
	 * Perform an actual JNDI lookup for the given name via the JndiTemplate.
   * <p>If the name doesn't begin with "java:comp/env/", this prefix is added
	 * if "resourceRef" is set to "true".
	 * @param jndiName the JNDI name to look up
	 * @return the obtained object
	 * @throws NamingException if the JNDI lookup failed
	 * @see #setResourceRef
	 */
	/**
	 *通过JndiTemplate为给定的名称执行实际的JNDI查找。
   *<p>如果名称不是以“java:comp/env/”开头，则会添加此前缀
	 *如果“resourceRef”设置为“true”。
	 *@param jndiName要查找的JNDI名称
	 *@返回获取的对象
	 *如果JNDI查找失败，@throws NamingException
	 *@参见#setResourceRef
	 */
	protected Object lookup(String jndiName) throws NamingException {
		return lookup(jndiName, null);
	}

	/**
	 * Perform an actual JNDI lookup for the given name via the JndiTemplate.
	 * <p>If the name doesn't begin with "java:comp/env/", this prefix is added
	 * if "resourceRef" is set to "true".
	 * @param jndiName the JNDI name to look up
	 * @param requiredType the required type of the object
	 * @return the obtained object
	 * @throws NamingException if the JNDI lookup failed
	 * @see #setResourceRef
	 */
	/**
	 *通过JndiTemplate为给定的名称执行实际的JNDI查找。
	 *<p>如果名称不是以“java:comp/env/”开头，则会添加此前缀
	 *如果“resourceRef”设置为“true”。
	 *@param jndiName要查找的JNDI名称
	 *@param requiredType所需的对象类型
	 *@返回获取的对象
	 *如果JNDI查找失败，@throws NamingException
	 *@参见#setResourceRef
	 */
	protected <T> T lookup(String jndiName, @Nullable Class<T> requiredType) throws NamingException {
		Assert.notNull(jndiName, "'jndiName' must not be null");
		String convertedName = convertJndiName(jndiName);
		T jndiObject;
		try {
			jndiObject = getJndiTemplate().lookup(convertedName, requiredType);
		}
		catch (NamingException ex) {
			if (!convertedName.equals(jndiName)) {
				// Try fallback to originally specified name...
				// 尝试回退到最初指定的名称。。。
				if (logger.isDebugEnabled()) {
					logger.debug("Converted JNDI name [" + convertedName +
							"] not found - trying original name [" + jndiName + "]. " + ex);
				}
				jndiObject = getJndiTemplate().lookup(jndiName, requiredType);
			}
			else {
				throw ex;
			}
		}
		if (logger.isDebugEnabled()) {
			logger.debug("Located object with JNDI name [" + convertedName + "]");
		}
		return jndiObject;
	}

	/**
	 * Convert the given JNDI name into the actual JNDI name to use.
	 * <p>The default implementation applies the "java:comp/env/" prefix if
	 * "resourceRef" is "true" and no other scheme (e.g. "java:") is given.
	 * @param jndiName the original JNDI name
	 * @return the JNDI name to use
	 * @see #CONTAINER_PREFIX
	 * @see #setResourceRef
	 */
	/**
	 *将给定的JNDI名称转换为要使用的实际JNDI名称。
	 *<p>默认实现应用“java:comp/env/”前缀，如果
	 *“resourceRef”是“true”，并且没有给出其他方案（例如“java:”）。
	 *@param jndiName原始JNDI名称
	 *@返回要使用的JNDI名称
	 *@参见#CONTAINER_PRIFIX
	 *@参见#setResourceRef
	 */
	protected String convertJndiName(String jndiName) {
		// Prepend container prefix if not already specified and no other scheme given.
		// 如果尚未指定并且未给定其他方案，请在容器前缀前加前缀。
		if (isResourceRef() && !jndiName.startsWith(CONTAINER_PREFIX) && jndiName.indexOf(':') == -1) {
			jndiName = CONTAINER_PREFIX + jndiName;
		}
		return jndiName;
	}

}
